Message Passing(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 1 - Introduction to Printing With QuickDraw GX / About QuickDraw GX Printing

Message Passing
QuickDraw GX printing features are based on a message-passing architecture. The messaging technology used with QuickDraw GX is described in the Message Manager chapter of Inside Macintosh: QuickDraw GX Environment and Utilities. This section provides you with a brief overview so that you can respond to messages passed to your application.
QuickDraw GX sends printing messages when certain printing-related tasks need to be accomplished or when certain printing-related conditions arise, such as when a print dialog box is displayed or the user moves the dialog box. A printing message is a value that QuickDraw GX passes down a chain of message handlers. A message handler is the recipient of a message and can include the application, the printer driver, and any printing extensions. The message chain consists of eligible message handlers.
The application can install itself as a message handler for particular messages. Typically, these messages relate to dialog boxes. The message handler specifies the code to execute when the message is received. This code is called an override function because it overrides the actions of the other message handlers by changing the behavior associated with the message.
The override function can forward the message so that other message handlers can act on it. This situation is described as a partial override. If the function does not forward the message, the situation is described as a total override because other message handlers do not have a chance to act on the message.
If you are in doubt about whether to create a total override or not, try a partial override first because a total override may prevent an overlooked piece of code from being executed. For example, someone could provide a printing extension after your application has been distributed. The printing extension may rely on intercepting a message that was not previously required to be forwarded by your application and, thus, create an incompatibility between your application and the printing extension.
Two examples follow that show the typical cases in which an application needs to override QuickDraw GX messages. The first example shows how messages are involved in displaying a dialog box. The second example shows how a message is involved in handling movable dialog boxes.
When the user chooses the Print menu item, your application may wish to add a panel to the Print dialog box before it is displayed. Because you want the printer driver to provide the default dialog box, you install a message handler so you can override the Print dialog box message, gxJobPrintDialog. Figure 1-9 shows how this override happens with several message handlers in a message chain: the application, a printing extension, a printer driver, and QuickDraw GX.
Figure 1-9 Message handlers in a message chain

The application calls the GXJobPrintDialog function to display the dialog box. This function also causes QuickDraw GX to pass the gxJobPrintDialog message down the message chain, starting with the application. Because the application installed a function to respond to this message, the application's override function is called. (The override function is not shown in Figure 1-9.)
The override function is an application-defined function that is executed when QuickDraw GX sends the application the gxJobPrintDialog message. The override function adds a panel to the dialog box and forwards the message. By forwarding a message, each handler in the message chain--the application, printer driver, and printing extensions--participates in building the dialog box. The chapter "Page Formatting and Dialog Box Customization" in this book discusses the messages your application must override to add panels to QuickDraw GX movable modal dialog boxes.
Figure 1-10 shows an application that installs a function to be called when QuickDraw GX sends the gxPrintingEvent message. QuickDraw GX sends this message in response to an event, which allows the application to redraw a portion of the screen if the event is an update event caused by the user moving the dialog box.
Figure 1-10 Overriding the gxPrintingEvent message

The override function that responds to the message has the responsibility to determine the kind of event that occurred and to redraw the invalid part of its windows if the event is an update event. This override function does not need to forward the message in this case because once the task is done, no other handler needs to take action. Thus, the function provides a total override of the gxPrintingEvent message in this case. For an example of an override function for this message, see the chapter "Core Printing Features" in this book.